<HTML>
<HEAD>
<TITLE> SPICE Kernel Pool Required Reading </TITLE>
</HEAD>

<BODY style="color: rgb(0, 0, 0); background-color: rgb(255, 255, 255);">

<A NAME="top"></A>

<TABLE STYLE="text-align: left; margin-left: auto; margin-right: auto; width: 800px;" BORDER="0" CELLPADDING="5" CELLSPACING="2">
<TBODY>
<TR>
  <TD STYLE="background-color: rgb(153, 153, 153); vertical-align: middle; text-align: center;">
  <DIV ALIGN="right">
    <SMALL><SMALL><A HREF="index.html">Index Page</A></SMALL></SMALL>
  </DIV>
  <B>SPICE Kernel Pool Required Reading</B> </TD>
</TR>
<TR>
  <TD STYLE="vertical-align: top;">

<H2> Table of Contents
</H2>

<PRE>
   <A HREF="#SPICE Kernel Pool Required Reading">SPICE Kernel Pool Required Reading</A>
      <A HREF="#Abstract">Abstract</A>
      <A HREF="#Managing Kernels">Managing Kernels</A>
         <A HREF="#The Generic Kernel Loader furnsh_c">The Generic Kernel Loader furnsh_c</A>
         <A HREF="#Kernel Priority">Kernel Priority</A>
         <A HREF="#Path Symbols">Path Symbols</A>
         <A HREF="#Keeping Track of Loaded Kernels">Keeping Track of Loaded Kernels</A>
         <A HREF="#Reloading Kernels">Reloading Kernels</A>
         <A HREF="#Load Limits">Load Limits</A>
         <A HREF="#Finding Out What's Loaded">Finding Out What's Loaded</A>
         <A HREF="#Unloading Kernels">Unloading Kernels</A>
         <A HREF="#Loading of Non-native Text and Binary Kernels">Loading of Non-native Text and Binary Kernels</A>
      <A HREF="#SPICE File Identification Word">SPICE File Identification Word</A>
      <A HREF="#Introduction of Text Kernels and Kernel Pool">Introduction of Text Kernels and Kernel Pool</A>
      <A HREF="#The SPICE Text Kernel File Format">The SPICE Text Kernel File Format</A>
         <A HREF="#String Continuation">String Continuation</A>
      <A HREF="#Fetching Data from the Kernel Pool">Fetching Data from the Kernel Pool</A>
         <A HREF="#Informational Functions">Informational Functions</A>
         <A HREF="#Changing Kernel Pool Contents">Changing Kernel Pool Contents</A>
         <A HREF="#Detecting Changes in the Kernel Pool">Detecting Changes in the Kernel Pool</A>
      <A HREF="#SPICE Subsystems that Rely on SPICE Text Kernels">SPICE Subsystems that Rely on SPICE Text Kernels</A>
         <A HREF="#PCK-related Functions">PCK-related Functions</A>
         <A HREF="#Time Conversion Functions">Time Conversion Functions</A>
         <A HREF="#Frame Transformation Functions">Frame Transformation Functions</A>
         <A HREF="#Instrument Description Functions">Instrument Description Functions</A>
      <A HREF="#Summary of Functions">Summary of Functions</A>

</PRE>

<HR SIZE=3 NOSHADE>

<BR><BR>
<A NAME="SPICE Kernel Pool Required Reading"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H1> SPICE Kernel Pool Required Reading
</H1><HR SIZE=3 NOSHADE><P><BR><BR><BR>
   Last revised on 2009 APR 08 by B. V. Semenov.
<P>
 
<BR><BR>
<A NAME="Abstract"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Abstract
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The CSPICE kernel subsystem serves to load and unload SPICE kernel
   files, retrieve loaded data, and directly insert data into the ``kernel
   pool''.
<P>
 
<BR><BR>
<A NAME="Managing Kernels"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Managing Kernels
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="The Generic Kernel Loader furnsh_c"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> The Generic Kernel Loader <a href="../cspice/furnsh_c.html">furnsh_c</a>
</H3><P><BR><BR>
   For the SPICE system to use kernel files, the files must be made known
   to the system and opened at run time. This activity is called
   ``loading'' kernels. CSPICE provides a simple function interface for
   this purpose. The principal kernel loading function is called <a href="../cspice/furnsh_c.html">furnsh_c</a>
   (pronounced ``furnish''). The kernel system also provides a small set of
   functions that enable an application to find the names and attributes of
   kernels that have been loaded via <a href="../cspice/furnsh_c.html">furnsh_c</a>.
<P>
 
   Previous versions of CSPICE loaded kernels using functions specific to
   each kernel type: SPK, CK, PCK, IK, LSK, EK; the binary kernel systems
   also supported a kernel unload facility. CSPICE continues to provide the
   original kernel loaders and unloaders, but you should use <a href="../cspice/furnsh_c.html">furnsh_c</a> to
   load SPICE kernels.
<P>
 
   NAIF recommends that when loading multiple kernels, rather than
   sequential calls to <a href="../cspice/furnsh_c.html">furnsh_c</a>, use a ``metakernel.'' A metakernel is a
   SPICE text kernel that lists the names of the kernels to load. At run
   time, the application supplies the name of the metakernel as an input
   argument to <a href="../cspice/furnsh_c.html">furnsh_c</a>. For example, instead of loading kernels using the
   code fragment:
<P>
 
<PRE>
   #include "SpiceUsr.h"
        .
        .
        .
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "leapseconds.ker"  );
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "mgs.tsc"          );
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "generic.bsp"      );
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "mgs.bc"           );
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "earth.bpc"        );
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "mgs.bes"          );
</PRE>
   one now may write
<P>
 
<PRE>
   #include "SpiceUsr.h"
        .
        .
        .
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( "kernels.txt" );
 
</PRE>
   where the file kernels.txt is a SPICE text kernel containing the lines
<P>
 
<PRE>
   \begindata
 
   KERNELS_TO_LOAD = ( 'leapseconds.ker',
                       'mgs.tsc',
                       'generic.bsp',
                       'mgs.bc',
                       'earth.bpc',
                       'mgs.bes'           )
 
   \begintext
</PRE>
   This technique has the advantage of enabling a user to change the set of
   kernels loaded by the application without modifying source code.
<P>
 
   It also possible to use <a href="../cspice/furnsh_c.html">furnsh_c</a> to load kernels in the older CSPICE
   style: the names of kernels to load can be supplied as input arguments
   to <a href="../cspice/furnsh_c.html">furnsh_c</a>. For example, instead of using the series of loader calls
   shown earlier, one now may write
<P>
 
<PRE>
   #include "SpiceUsr.h"
        .
        .
        .
 
   #define NKER  6
 
   char  * kernels[NKER] = {  "leapseconds.ker",
                              "mgs.tsc",
                              "generic.bsp",
                              "mgs.bc",
                              "earth.bpc",
                              "mgs.bes"        };
 
   for ( int i = 0;  i &lt; NKER;  i++ )
      {
      <a href="../cspice/furnsh_c.html">furnsh_c</a> ( kernels[i] );
      }
</PRE>
<BR><BR>
<A NAME="Kernel Priority"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Kernel Priority
</H3><P><BR><BR>
   The older CSPICE loaders allow users to prioritize kernel files via load
   order: kernels loaded later have higher priority than kernels loaded
   earlier. <a href="../cspice/furnsh_c.html">furnsh_c</a> follows the same convention. When kernels are listed
   in a metakernel, those appearing later in the list have higher priority.
   The old prioritization scheme also applies to kernels supplied directly
   as arguments to <a href="../cspice/furnsh_c.html">furnsh_c</a>.
<P>
 
<BR><BR>
<A NAME="Path Symbols"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Path Symbols
</H3><P><BR><BR>
   Inside a metakernel, it is sometimes necessary to qualify file names
   with their pathnames. To reduce both typing and the need to continue
   file names over multiple lines, metakernels allow users to define
   symbols for paths. This is done using the kernel variables
<P>
 
<PRE>
   PATH_VALUES
   PATH_SYMBOLS
</PRE>
   To create symbols for path names, one assigns an array of path names to
   the variable PATH_VALUES. Next, one assigns an array of corresponding
   symbol names to the variable PATH_SYMBOLS. The nth symbol in the second
   array represents the nth path name in the first.
<P>
 
   Finally, one prefixes with path symbols the kernel names specified in
   the KERNELS_TO_LOAD variable. Each symbol is prefixed with a dollar sign
   to indicate that it is in fact a symbol.
<P>
 
   Suppose in our example above that the MGS kernels reside in the path
<P>
 
<PRE>
   /flight_projects/mgs/SPICE_kernels
</PRE>
   and the other kernels reside in the path
<P>
 
<PRE>
   /generic/SPICE_kernels
</PRE>
   Then we can add paths to our metakernel as follows:
<P>
 
<PRE>
   \begindata
 
   PATH_VALUES  = ( '/flight_projects/mgs/SPICE_kernels',
                    '/generic/SPICE_kernels'              )
 
   PATH_SYMBOLS = ( 'MGS',
                    'GEN' )
 
 
   KERNELS_TO_LOAD = ( '$GEN/leapseconds.ker',
                       '$MGS/mgs.tsc',
                       '$GEN/generic.bsp',
                       '$MGS/mgs.bc',
                       '$GEN/earth.bpc',
                       '$MGS/mgs.bes'           )
 
   \begintext
</PRE>
   It is not required that paths be abbreviated using path symbols; it's
   simply a convenience.
<P>
 
   Note the symbols defined here are not related to the symbols supported
   by a host shell or any other operating system interface.
<P>
 
<BR><BR>
<A NAME="Keeping Track of Loaded Kernels"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Keeping Track of Loaded Kernels
</H3><P><BR><BR>
   <a href="../cspice/furnsh_c.html">furnsh_c</a> maintains a record of the load operations it has performed
   during a program run. This record is implemented using data structures
   of fixed size, so there is a limit on the number of the maximum number
   of loaded kernels <a href="../cspice/furnsh_c.html">furnsh_c</a> can accommodate.
<P>
 
   When a loaded kernel is loaded via <a href="../cspice/furnsh_c.html">furnsh_c</a>, a new entry is created in
   the record of loaded kernels, whether or not the kernel is already
   loaded.
<P>
 
   All load or unload (see the discussion of <a href="../cspice/unload_c.html">unload_c</a> below) operations
   affect the list of loaded files and therefore affect the results
   returned by the routines <a href="../cspice/ktotal_c.html">ktotal_c</a>, <a href="../cspice/kdata_c.html">kdata_c</a>, and <a href="../cspice/kinfo_c.html">kinfo_c</a>, all of which
   are discussed below under ``Finding Out What's Loaded.''
<P>
 
<BR><BR>
<A NAME="Reloading Kernels"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Reloading Kernels
</H3><P><BR><BR>
   Reloading an already loaded kernel decreases the available space in
   <a href="../cspice/furnsh_c.html">furnsh_c</a>'s list of loaded files. furnsh_c's treatment of reloaded files
   is thus slightly different from that performed by the CSPICE low-level
   kernel loaders, which handle a reload operation by first unloading the
   kernel in question, then loading it.
<P>
 
   The recommended method of increasing the priority of a loaded binary
   kernel, or of a metakernel containing binary kernels, is to unload it
   using <a href="../cspice/unload_c.html">unload_c</a> (see below), then reload it using <a href="../cspice/furnsh_c.html">furnsh_c</a>. This
   technique helps reduce clutter in <a href="../cspice/furnsh_c.html">furnsh_c</a>'s kernel list.
<P>
 
<BR><BR>
<A NAME="Load Limits"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Load Limits
</H3><P><BR><BR>
   <a href="../cspice/furnsh_c.html">furnsh_c</a> can currently keep track of up to 1300 kernels. The list of
   loaded kernels may contain multiple entries for a given physical file,
   so the number of maximum number of distinct loaded files may be smaller
   if some files have been reloaded. Unloading kernels via <a href="../cspice/unload_c.html">unload_c</a> frees
   room in the file list, so there is no limit on the total number of load
   or unload operations performed in a program run.
<P>
 
   The DAF/DAS handle manager system imposes its own lower limit on the
   number of DAF and DAS files that may be loaded simultaneously. This
   limit is currently set to a total of 1000 DAF and DAS files.
<P>
 
<BR><BR>
<A NAME="Finding Out What's Loaded"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Finding Out What's Loaded
</H3><P><BR><BR>
   CSPICE-based applications may need to determine at run time which files
   have been loaded. Applications may need to find the DAF or DAS handles
   of loaded binary kernels so that the kernels may be searched. Some
   applications may need to unload kernels to make room for others, or
   change the priority of loaded kernels at run time.
<P>
 
   CSPICE provides kernel access routines to support these needs. For every
   loaded kernel, an application can find the name of kernel, the kernel
   type (text or one of SPK, CK, PCK, or EK), the kernel's DAF or DAS
   handle if applicable, and the name of the metakernel used to load the
   kernel, again if applicable.
<P>
 
   The function <a href="../cspice/ktotal_c.html">ktotal_c</a> returns the count of loaded kernels of a given
   type. The function <a href="../cspice/kdata_c.html">kdata_c</a> returns information on the nth kernel of a
   given type. The two functions are normally used together. Following is
   an example of how an application could retrieve summary information on
   the currently loaded SPK files:
<P>
 
<PRE>
      #include &lt;stdio.h&gt;
      #include "SpiceUsr.h"
 
      #define  FILLEN   128
      #define  TYPLEN   32
      #define  SRCLEN   128
 
      SpiceInt        which;
      SpiceInt        handle;
 
      SpiceChar       file  [FILLEN];
      SpiceChar       filtyp[TYPLEN];
      SpiceChar       source[SRCLEN];
 
      SpiceBoolean    found;
           .
           .
           .
 
      <a href="../cspice/ktotal_c.html">ktotal_c</a> ( "spk", &amp;count );
 
      if ( count == 0 )
         {
         printf ( "No SPK files loaded at this time.\n" );
         }
      else
         {
         printf ( "The loaded SPK files are: \n\n" );
         }
 
      for ( which = 0;  which &lt; count;  which++ )
         {
         <a href="../cspice/kdata_c.html">kdata_c</a> ( which,  "spk",    FILLEN,   TYPLEN, SRCLEN,
                   file,   filtyp,  &amp;source, &amp;handle,  &amp;found );
         printf ( "%s\n",  file   );
         }
</PRE>
   Above, the input argument "spk" is a kernel type specifier. The allowed
   set of values is
<P>
 
<PRE>
   SPK  --- All SPK files are counted in the total.
   CK   --- All CK files are counted in the total.
   PCK  --- All binary PCK files are counted in the
            total.
   EK   --- All EK files are counted in the total.
   TEXT --- All text kernels that are not meta-text
            kernels are included in the total.
   META --- All meta-text kernels are counted in the
            total.
   ALL  --- Every type of kernel is counted in the
            total.
</PRE>
   In this example, `filtyp' is a string indicating the type of kernel.
   `handle' is the file handle if the file is a binary SPICE kernel.
   `source' is the name of the metakernel used to load the file, if
   applicable. `found' indicates whether a file having the specified type
   and index was found.
<P>
 
   CSPICE also contains the function <a href="../cspice/kinfo_c.html">kinfo_c</a> which returns summary
   information about a file whose name is already known. <a href="../cspice/kinfo_c.html">kinfo_c</a> is called
   as follows:
<P>
 
<PRE>
      <a href="../cspice/kinfo_c.html">kinfo_c</a> ( file,   TYPLEN, SRCLEN,
                filtyp, source, &amp;handle, &amp;found );
</PRE>
<BR><BR>
<A NAME="Unloading Kernels"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Unloading Kernels
</H3><P><BR><BR>
   CSPICE-based applications may need to remove loaded kernels. Possible
   reasons for this are:
<P>
 
<UL>
<TT>--</TT> To make room to load other kernels.
<BR><BR></UL>
<UL>
<TT>--</TT> To change the priority of loaded kernel data.
<BR><BR></UL>
<UL>
<TT>--</TT> To change the set of kernel data visible to CSPICE.
<BR><BR></UL>
   The function <a href="../cspice/unload_c.html">unload_c</a> acts as an inverse to <a href="../cspice/furnsh_c.html">furnsh_c</a>: passing a kernel
   to <a href="../cspice/unload_c.html">unload_c</a> undoes the effect of the last load operation performed on
   that kernel via <a href="../cspice/furnsh_c.html">furnsh_c</a>. For binary kernels that have been loaded just
   once, the meaning of this is simple: the kernel is closed, and CSPICE
   data structures referring to the file's contents are adjusted to reflect
   the absence of the file.
<P>
 
   Text kernels and metakernels may be unloaded as well. Unloading a
   metakernel involves unloading the files referenced by the metakernel.
   Text kernels are unloaded by clearing the kernel pool and then reloading
   the other text kernels not designated for removal.
<P>
 
   Note that unloading text kernels has the side effect of wiping out
   kernel variables that have been set via the kernel pool's function write
   access interface. It is important to consider whether this side effect
   is acceptable when writing code that may unload text kernels or
   metakernels.
<P>
 
   <a href="../cspice/unload_c.html">unload_c</a> is called as follows:
<P>
 
<PRE>
      <a href="../cspice/unload_c.html">unload_c</a> ( kernel );
</PRE>
<BR><BR>
<A NAME="Loading of Non-native Text and Binary Kernels"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Loading of Non-native Text and Binary Kernels
</H3><P><BR><BR>
   The various platforms supported by CSPICE use different end-of-line
   (EOL) indicators in text files:
<P>
 
<PRE>
 
   Environment                  Native End-Of-Line
                                Indicator
   ___________                  _____________________
 
   PC DOS/Windows                &lt;CR&gt;&lt;LF&gt;
   Unix                          &lt;LF&gt;
   Linux                         &lt;LF&gt;
   Alpha  Digital Unix           &lt;LF&gt;
   Mac OS X                      &lt;LF&gt;
   Macintosh Classic (OS9)       &lt;CR&gt;
 
</PRE>
   As of CSPICE N0059, the CSPICE text kernel loaders, <a href="../cspice/furnsh_c.html">furnsh_c</a> and
   <a href="../cspice/ldpool_c.html">ldpool_c</a>, can read and parse non-native text files. The FORTRAN SPICELIB
   does not include this capability.
<P>
 
   Please be aware the CSPICE text file reader, <a href="../cspice/rdtext_c.html">rdtext_c</a>, does not possess
   the capability to read non-native text files.
<P>
 
   Starting with the N0052 release of the SPICE Toolkit (January, 2002)
   certain supported platforms are able to read DAF-based binary files
   (SPK, CK and binary PCK) that were written using a different, or
   non-native, binary representation. This access is read-only; any
   operations requiring writing to the file (adding information to the
   comment area, or appending additional ephemeris data, for example)
   require prior conversion of the file to the native binary file format.
   See the Convert User's Guide, <a href="../ug/convert.html">convert.ug</a>, for details.
<P>
 
<BR><BR>
<A NAME="SPICE File Identification Word"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> SPICE File Identification Word
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The first few bytes of a SPICE kernel are used for the SPICE file
   identification word. In binary and text kernels this word consists of
   two string IDs separated by the ``/'' character. The first ID,
   identifying the file architecture of the SPICE kernel file (``DAF'',
   ``DAS'', ``KPL'', etc), is always three characters long. The second ID
   identifying the file type of the SPICE kernel file (``SPK'', ``PCK'',
   ``IK'', ``SCLK'', etc), is two to four characters long. In transfer
   format files (see <a href="../ug/convert.html">convert.ug</a> for details) this word consists of a single
   string ID.
<P>
 
   In binary kernels the SPICE file identification word always occupies the
   first eight bytes. If the combined length of the file architecture ID,
   ``/'', and the file type ID is less than 8 characters, the word is
   padded on the right to eight characters using blanks (e.g. ``DAF/SPK '',
   ``DAS/EK '', etc). The correct file identification word is written to a
   binary file automatically when the file is created by calling the kernel
   type specific ``open new file'' routine -- <a href="../cspice/spkopn_c.html">spkopn_c</a> for SPK files,
   <a href="../cspice/ckopn_c.html">ckopn_c</a> for CK files, etc. If a binary file is created by calling the
   architecture specific ``open new file'' routine -- dafonw_c for DAF
   files, dasonw_c for DAS files, etc, -- it is the caller's responsibility
   to specify the correct kernel type in the corresponding input argument
   of these routines to make sure the correct SPICE file identification
   word is written to the file.
<P>
 
   In text kernels the SPICE file identification word occupies the first
   six to eight characters and is immediately followed by the end-of-line
   terminator character(s), resulting in the identification word appearing
   on a line by itself. If the combined length of the file architecture ID,
   ``/'', and the file type ID is less than 8 characters, the word can but
   does not have to be padded on the right to eight characters using blanks
   (e.g. ``KPL/SCLK'', ``KPL/IK'', etc). Since most text kernels are
   created manually using a text editor, it is the responsibility of the
   person who makes the file to put the correct SPICE file identification
   word by itself on the first line of the file.
<P>
 
   In transfer format files the SPICE file identification word occupies the
   first six characters of the file and is followed by the expanded name of
   the format (e.g. ``DAFETF NAIF DAF ENCODED TRANSFER FILE''). The correct
   file identification word is written to a transfer format file
   automatically when the file is created by the SPICE utility programs
   TOXFR or SPACIT (see <a href="../ug/toxfr.html">toxfr.ug</a> and <a href="../ug/spacit.html">spacit.ug</a> for details).
<P>
 
   This table lists the SPICE file identification words used in modern
   SPICE kernel types:
<P>
 
<PRE>
   Binary Kernels:
 
      SPK           DAF/SPK
      CK            DAF/CK
      PCK           DAF/PCK
      EK            DAS/EK
 
   Text Kernels:
 
      FK            KPL/FK
      IK            KPL/IK
      LSK           KPL/LSK
      MK            KPL/MK
      PCK           KPL/PCK
      SCLK          KPL/SCLK
 
   Transfer format files:
 
      DAF           DAFETF
      DAS           DASETF
 
</PRE>
   The Toolkit includes the <a href="../cspice/getfat_c.html">getfat_c</a> routine that can be used to retrieve
   the kernel file architecture and type encapsulated in the SPICE file
   identification word.
<P>
 
<BR><BR>
<A NAME="Introduction of Text Kernels and Kernel Pool"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Introduction of Text Kernels and Kernel Pool
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   A variety of SPICE text kernels that are read into and accessed through
   the kernel pool. These include:
<P>
 
<UL>
<TT>--</TT> Text PCK kernels
<BR><BR></UL>
<UL>
<TT>--</TT> Leapseconds kernels
<BR><BR></UL>
<UL>
<TT>--</TT> SCLK kernels
<BR><BR></UL>
<UL>
<TT>--</TT> I kernels
<BR><BR></UL>
<UL>
<TT>--</TT> Frame kernels
<BR><BR></UL>
   Do not confuse SPICE text kernels with text ``transfer'' versions of
   SPK, CK, PCK or DAF files produced by the utilities SPACIT or TOXFR. The
   text transfer files are not intended to be used with the kernel pool and
   do not conform to the SPICE text kernel format.
<P>
 
   The kernel pool system interface is composed of two parts: a text file
   format and kernel pool access software. The software includes functions
   that read files conforming to the format, routines that allow direct
   insertion of data into the pool via function calls, functions that fetch
   data from the kernel pool, functions that return information about the
   current state of the pool, and utilities that manipulate various aspects
   of the pool.
<P>
 
   The SPICE text kernel format has a ``name = value'' structure similar to
   the format used to assign values to variables in languages such as C and
   FORTRAN. Details of the format are described below.
<P>
 
   The kernel pool may be viewed abstractly as a repository of associative
   arrays which map names to lists of numeric or string values. The kernel
   pool allows CSPICE-based programs to read data from SPICE text kernel
   files while maintaining the ``name = value'' associations established in
   the files. Alternatively, associative arrays may be inserted into the
   kernel pool via the pool's programming interface.
<P>
 
   Once name-value associations have been stored in the kernel pool, you
   may access the stored data through kernel pool look-up functions. These
   look-up functions use the names as keys to find the associated values.
   The look-up and other access functions are described in detail below.
<P>
 
<BR><BR>
<A NAME="The SPICE Text Kernel File Format"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> The SPICE Text Kernel File Format
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   As the name implies, SPICE text kernel files contain only ASCII text. An
   additional restriction on the contents of SPICE text kernel files is
   that they contain no non-printing characters, such as tabs or formfeeds.
<P>
 
   We illustrate this format by way of example using an excerpt from a
   SPICE text planetary constants kernel (PCK) file. The format description
   given below applies to all SPICE text kernels; the specific data names
   shown below apply only to text PCK files.
<P>
 
<PRE>
   Planets first. Each has quadratic expressions for the direction
   (RA, Dec) of the north pole and the rotation of the prime meridian.
   Planets with satellites (except Pluto) also have linear expressions
   for the auxiliary (phase) angles used in the nutation and libration
   expressions of their satellites.
 
   \begindata
 
   BODY399_POLE_RA        = (    0.      -0.64061614  -0.00008386  )
   BODY399_POLE_DEC       = (  +90.      -0.55675303  +0.00011851  )
   BODY399_PM             = (   10.21  +360.98562970  +0.          )
   BODY399_LONG_AXIS      = (    0.                                )
 
   BODY3_NUT_PREC_ANGLES  = (  125.045    -1935.53
                               249.390    -3871.06
                               196.694  -475263.
                               176.630  +487269.65
                               358.219   -36000.    )
 
   \begintext
 
   Each satellite has similar quadratic expressions for the pole and
   prime meridian. In addition, some satellites have nonzero nutation
   and libration amplitudes. (The number of amplitudes matches the
   number of auxiliary phase angles of the primary.)
 
   \begindata
 
   BODY301_POLE_RA      = (  270.000   -0.64061614  -0.00008386   )
   BODY301_POLE_DEC     = (  +66.534   -0.55675303  +0.00011851   )
   BODY301_PM           = (   38.314  +13.1763581    0.           )
   BODY301_LONG_AXIS    = (    0.                                 )
 
   BODY301_NUT_PREC_RA  = (  -3.878  -0.120  +0.070  -0.017   0.     )
   BODY301_NUT_PREC_DEC = (  +1.543  +0.024  -0.028  +0.007   0.     )
   BODY301_NUT_PREC_PM  = (  +3.558  +0.121  -0.064  +0.016  +0.025  )
 
   \begintext
 
   Finally, we include the radii of the satellites and planets.
 
   \begindata
 
   BODY399_RADII    = (     6378.140    6378.140     6356.755  )
   BODY301_RADII    = (     1738.       1738.        1738.     )
 
   \begintext
</PRE>
   In this example are several comment blocks. All are introduce by the
   control word:
<P>
 
<PRE>
   \begintext
</PRE>
   A comment block may contain any number of comment lines. Once a comment
   block has begun, no special characters are required to introduce
   subsequent lines of comments within that block. A comment block is
   terminated by the control word
<P>
 
<PRE>
   \begindata
</PRE>
   This control word also serves to introduce a block of data that will be
   stored in the kernel pool. Each of these control words must appear on a
   line by itself.
<P>
 
   Each variable definition consists of three components:
<P>
 
<UL>
<TT>1.</TT> A variable name.
<BR><BR></UL>
<UL>
<TT>2.</TT> An assignment directive. This must be ``='' (direct assignment) or ``+=''
(incremental assignment).
<BR><BR></UL>
<UL>
<TT>3.</TT> A scalar or vector value.
<BR><BR></UL>
   A variable name can include any printable the character except:
<P>
 
<UL>
<TT>1.</TT> `` '' (space)
<BR><BR></UL>
<UL>
<TT>2.</TT> ``.'' (period)
<BR><BR></UL>
<UL>
<TT>3.</TT> ``('' (open parentheses)
<BR><BR></UL>
<UL>
<TT>4.</TT> ``)'' (close parentheses)
<BR><BR></UL>
<UL>
<TT>5.</TT> ``=" (equal sign)
<BR><BR></UL>
<UL>
<TT>6.</TT> TAB character
<BR><BR></UL>
   NAIF recommends you do not use a variable name with ``+' as the last
   character.
<P>
 
   Direct assignments supersede previous assignments, whereas incremental
   assignments are added to previous assignments. For example, the series
   of assignments
<P>
 
<PRE>
   BODY301_NUT_PREC_RA  = -3.878
   BODY301_NUT_PREC_RA += -0.120
   BODY301_NUT_PREC_RA += +0.070
   BODY301_NUT_PREC_RA += -0.017
   BODY301_NUT_PREC_RA += 0.
</PRE>
   has the same effect as the single assignment
<P>
 
<PRE>
   BODY301_NUT_PREC_RA = (  -3.878  -0.120  +0.070  -0.017   0 )
</PRE>
   Dates, e.g.,
<P>
 
<PRE>
   FOOBAR_CALIBRATION_DATES = ( @31-JAN-1987,
                                @2/4/87,
                                @March-7-1987-3:10:39.221 )
</PRE>
   may be entered in a wide variety of formats. There are two restrictions
   regarding the format of dates. They may not contain embedded blanks, and
   they must begin with the character
<P>
 
<PRE>
   @
</PRE>
   Internally, dates are converted to TDB seconds past J2000 as they are
   read. As a result, dates, are treated as numeric data in the pool.
<P>
 
   Strings may be supplied by quoting the string value.
<P>
 
<PRE>
   MISSION_UNITS = ( 'KILOMETERS',
                     'SECONDS',
                     'KILOMETERS/SECOND' )
</PRE>
   If you need to include a quote in the string value, use the FORTRAN
   convention of "doubling" the quote.
<P>
 
<PRE>
   MESSAGE = ( 'You can''t always get what you want.' )
</PRE>
   The maximum length of as string that can be assigned as the value of a
   scalar kernel variable, or as an element of an array-valued kernel
   variable, is 80 characters.
<P>
 
   The types of values assigned to a kernel pool variable must all be the
   same. If you attempt to make an assignment such as the one shown here:
<P>
 
<PRE>
   ERROR_EXAMPLE = ( 1, 2, 'THREE', 4, 'FIVE' )
</PRE>
   The kernel pool reader will regard the assignment as erroneous and
   reject it and any subsequent kernel pool assignments that appear in the
   text kernel.
<P>
 
<BR><BR>
<A NAME="String Continuation"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> String Continuation
</H3><P><BR><BR>
   It is possible to treat specified, consecutive components of a string
   array as a single ``continued'' string. String continuation is indicated
   by placing a user-specified sequence of non-blank characters at the end
   (excluding trailing blanks) of each string value that is to be
   concatenated to its successor. For example, if the character sequence
<P>
 
<PRE>
   //
</PRE>
   is used as a continuation mark, the assignment
<P>
 
<PRE>
   CONTINUED_STRINGS = ( 'This //  ',
                         'is //  ',
                         'just //',
                         'one long //',
                         'string.',
                         'Here''s a second //',
                         'continued //'
                         'string.'              )
</PRE>
   allows the string array elements on the right hand side of the
   assignment to be treated as the two strings
<P>
 
<PRE>
   This is just one long string.
   Here's a second continued string.
</PRE>
   The CSPICE function <a href="../cspice/stpool_c.html">stpool_c</a> provides the capability of retrieving
   continued strings from the kernel pool. See the discussion below under
   ``Fetching Data from the Kernel Pool'' or the header of <a href="../cspice/stpool_c.html">stpool_c</a> for
   further information.
<P>
 
<BR><BR>
<A NAME="Fetching Data from the Kernel Pool"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Fetching Data from the Kernel Pool
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   The values of variables stored in the kernel pool may be retrieved using
   the functions:
<P>
 
<DL><DT>
<B>
 <a href="../cspice/gcpool_c.html">gcpool_c</a>
</B><BR><BR>
<DD>
 Used to fetch character data from the kernel pool.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/gdpool_c.html">gdpool_c</a>
</B><BR><BR>
<DD>
 Used to fetch double precision data from the kernel pool.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/gipool_c.html">gipool_c</a>
</B><BR><BR>
<DD>
 Used to fetch integer data from the kernel pool. Note that internally,
all numeric data are stored as double precision values. This interface
is provided as a convenience so that users may retrieve integer data
directly from the kernel pool without having worry about converting
from double precision values to integers.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/stpool_c.html">stpool_c</a>
</B><BR><BR>
<DD>
 Used to fetch continued strings from the kernel pool.<BR>
</DL>
   The calling sequences are shown below.
<P>
 
<PRE>
   \literal
   <a href="../cspice/gcpool_c.html">gcpool_c</a>( name, first, room,   lenout,  nvalues, values, found );
   <a href="../cspice/gdpool_c.html">gdpool_c</a>( name, first, room,   nvalues, values,  found );
   <a href="../cspice/gipool_c.html">gipool_c</a>( name, first, room,   nvalues, values,  found );
   <a href="../cspice/stpool_c.html">stpool_c</a>( name, nth,   contin, lenout,  string,  size,   found );
</PRE>
   The meanings of the arguments are as follows:
<P>
 
<DL><DT>
<B>
 `name'
</B><BR><BR>
<DD>
 is the name of the item to retrieve.<BR>
</DL>
<DL><DT>
<B>
 `first'
</B><BR><BR>
<DD>
 is the index of the first item to retrieve from the array of values
associated with `name'.<BR>
</DL>
<DL><DT>
<B>
 `room'
</B><BR><BR>
<DD>
 is the number of values that may be stored in the output array
`values'.<BR>
</DL>
<DL><DT>
<B>
 `lenout'
</B><BR><BR>
<DD>
 is the maximum allowed length of the output string, including the
terminating null character.<BR>
</DL>
<DL><DT>
<B>
 `nvalues'
</B><BR><BR>
<DD>
 is the number of items stored in `values'<BR>
</DL>
<DL><DT>
<B>
 `values'
</B><BR><BR>
<DD>
 is the output array of values associated with `name'. The data type of
`values' depends upon the routine: for <a href="../cspice/gcpool_c.html">gcpool_c</a>, `values' is an array
of strings; for <a href="../cspice/gdpool_c.html">gdpool_c</a>, `values' is an array of double precision
numbers, for <a href="../cspice/gipool_c.html">gipool_c</a>, `values' is an array of integers.<BR>
</DL>
<DL><DT>
<B>
 `found'
</B><BR><BR>
<DD>
 indicates whether or not the requested data are is available in the
kernel pool.<BR>
</DL>
   For the function <a href="../cspice/stpool_c.html">stpool_c</a>
<P>
 
<DL><DT>
<B>
 `nth'
</B><BR><BR>
<DD>
 is the index of the continued string to fetch.<BR>
</DL>
<DL><DT>
<B>
 `contin'
</B><BR><BR>
<DD>
 is the continuation marker. This is a sequence of characters used to
indicate that the next string array element is to be concatenated to
the marked element.<BR>
</DL>
<DL><DT>
<B>
 `string'
</B><BR><BR>
<DD>
 is the string value whose index is given by `nth'.<BR>
</DL>
<DL><DT>
<B>
 `size'
</B><BR><BR>
<DD>
 is the number of characters in the returned string, excluding the
terminating null character.<BR>
</DL>
   See the headers of these functions for a more extensive discussion of
   their arguments and use.
<P>
 
<BR><BR>
<A NAME="Informational Functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Informational Functions
</H3><P><BR><BR>
   Four routines are provided for retrieving general information about the
   contents of the kernel pool.
<P>
 
<DL><DT>
<B>
 <a href="../cspice/dtpool_c.html">dtpool_c</a>
</B><BR><BR>
<DD>
 Returns information about the existence, dimension and type of kernel
pool variables.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/expool_c.html">expool_c</a>
</B><BR><BR>
<DD>
 Returns information on the existence of a kernel pool variable.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/gnpool_c.html">gnpool_c</a>
</B><BR><BR>
<DD>
 Allows retrieval of names of kernel pool variables that match a string
pattern.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/szpool_c.html">szpool_c</a>
</B><BR><BR>
<DD>
 Returns information about the size of various structures used in the
implementation of the kernel pool.<BR>
</DL>
   These routines are discussed at length in their respective headers.
<P>
 
<BR><BR>
<A NAME="Changing Kernel Pool Contents"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Changing Kernel Pool Contents
</H3><P><BR><BR>
   The main way in which you change the contents of the kernel pool is by
   ``loading'' a SPICE text kernel with the function <a href="../cspice/furnsh_c.html">furnsh_c</a>. However, the
   kernel pool also provides a several other routines that allow you to
   change the contents of the pool.
<P>
 
<DL><DT>
<B>
 <a href="../cspice/clpool_c.html">clpool_c</a>
</B><BR><BR>
<DD>
 clears (initializes) the kernel pool, deleting all the variables in the
pool.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/lmpool_c.html">lmpool_c</a>
</B><BR><BR>
<DD>
 Similar in effect to loading a text kernel via <a href="../cspice/furnsh_c.html">furnsh_c</a>, but the text
kernel is stored in an array of strings instead of an external file.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/pcpool_c.html">pcpool_c</a>
</B><BR><BR>
<DD>
 Allows the insertion of a character variable directly into the kernel
pool without supplying a text kernel.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/pdpool_c.html">pdpool_c</a>
</B><BR><BR>
<DD>
 Allows the insertion of a double precision variable directly into the
kernel pool without supplying a text kernel.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/pipool_c.html">pipool_c</a>
</B><BR><BR>
<DD>
 Allows the insertion of an integer variable directly into the kernel
pool without supplying a text kernel.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/dvpool_c.html">dvpool_c</a>
</B><BR><BR>
<DD>
 allows deletion of a specific variable from the kernel pool. (<a href="../cspice/clpool_c.html">clpool_c</a>
deletes all variables from the kernel pool.)<BR>
</DL>
   The following code fragment shows how the data normally provided in a
   leapseconds kernel could be loaded via <a href="../cspice/lmpool_c.html">lmpool_c</a>. See the headers of the
   other functions for specific details regarding their use.
<P>
 
<PRE>
   #include "SpiceUsr.h"
          .
          .
          .
   #define  LNSIZE      81
   #define  BUFSIZE     28
 
   static SpiceChar     text [BUFSIZE][LNSIZE] =
      {
      "DELTET/DELTA_T_A =   32.184",
      "DELTET/K         =    1.657D-3",
      "DELTET/EB        =    1.671D-2",
      "DELTET/M         = (  6.239996D0",
      "                      1.99096871D-7 )",
      "DELTET/DELTA_AT  = ( 10, @1972-JAN-1",
      "                     11, @1972-JUL-1",
      "                     12, @1973-JAN-1",
      "                     13, @1974-JAN-1",
      "                     14, @1975-JAN-1",
      "                     15, @1976-JAN-1",
      "                     16, @1977-JAN-1",
      "                     17, @1978-JAN-1",
      "                     18, @1979-JAN-1",
      "                     19, @1980-JAN-1",
      "                     20, @1981-JUL-1",
      "                     21, @1982-JUL-1",
      "                     22, @1983-JUL-1",
      "                     23, @1985-JUL-1",
      "                     24, @1988-JAN-1",
      "                     25, @1990-JAN-1",
      "                     26, @1991-JAN-1",
      "                     27, @1992-JUL-1",
      "                     28, @1993-JUL-1",
      "                     29, @1994-JUL-1",
      "                     30, @1996-JAN-1",
      "                     31, @1997-JUL-1",
      "                     32, @1999-JAN-1)"
      };
 
      /*
      Add the contents of the buffer to the kernel pool:
      */
      <a href="../cspice/lmpool_c.html">lmpool_c</a> ( text, BUFSIZE );
</PRE>
<BR><BR>
<A NAME="Detecting Changes in the Kernel Pool"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Detecting Changes in the Kernel Pool
</H3><P><BR><BR>
   Since loading SPICE text kernels tends to happen only at program
   initialization, a function that relies on data in the kernel pool may
   run more efficiently if it can store a local copy of the values needed
   and update these only when a change occurs in the kernel pool. Two
   functions are available that allow a quick test to see whether kernel
   pool variables have been updated.
<P>
 
<DL><DT>
<B>
 <a href="../cspice/swpool_c.html">swpool_c</a>
</B><BR><BR>
<DD>
 Sets up a "watcher" on a variable so that various "agents" can be
notified when a variable has been updated.<BR>
</DL>
<DL><DT>
<B>
 <a href="../cspice/cvpool_c.html">cvpool_c</a>
</B><BR><BR>
<DD>
 Indicates whether or not an agent's variable has been updated since the
last time an agent checked with the pool.<BR>
</DL>
   See the headers of these functions for details and examples of their
   use.
<P>
 
<BR><BR>
<A NAME="SPICE Subsystems that Rely on SPICE Text Kernels"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> SPICE Subsystems that Rely on SPICE Text Kernels
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
<BR><BR>
<A NAME="PCK-related Functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> PCK-related Functions
</H3><P><BR><BR>
   The PCK kernel is CSPICE's source of the planetary constants needed to
   define the size, shape, and orientation of planets and satellites. The
   PCK text file format and functions which access PCK data are described
   in the PCK Required Reading, <a href="../req/pck.html">pck.req</a>.
<P>
 
<BR><BR>
<A NAME="Time Conversion Functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Time Conversion Functions
</H3><P><BR><BR>
   Routines that retrieve leapseconds or SCLK data directly from the kernel
   pool are documented in the <a href="../req/time.html">time.req</a> and <a href="../req/sclk.html">sclk.req</a> Required reading files,
   respectively.
<P>
 
<BR><BR>
<A NAME="Frame Transformation Functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Frame Transformation Functions
</H3><P><BR><BR>
   See the FRAMES Required Reading, <a href="../req/frames.html">frames.req</a>, for a discussion of frame
   definition kernels.
<P>
 
<BR><BR>
<A NAME="Instrument Description Functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H3> Instrument Description Functions
</H3><P><BR><BR>
   Instrument kernels specify an instrument's field-of-view, size, shape,
   and orientation. Internal instrument timing parameters and other data
   relating to SPICE computations might also be placed in an I-kernel. Once
   an I-kernel containing the required keywords defining the instrument's
   FOV is loaded, the <a href="../cspice/getfov_c.html">getfov_c</a> routine can used to retrieve the FOV
   parameters.
<P>
 
<BR><BR>
<A NAME="Summary of Functions"></A>
<p align="right"><a href="#top"><small>Top</small></a></p>
<H2> Summary of Functions
</H2><HR ALIGN="LEFT" WIDTH=50% ><P><BR><BR>
   Each kernel pool function name consists of a mnemonic which translates
   into a short description of the function's purpose.
<P>
 
<PRE>
   <a href="../cspice/clpool_c.html">clpool_c</a> ( Clear the pool of kernel variables )
   <a href="../cspice/cvpool_c.html">cvpool_c</a> ( Check variable in the pool for update )
   <a href="../cspice/dtpool_c.html">dtpool_c</a> ( Data for a kernel pool variable )
   <a href="../cspice/dvpool_c.html">dvpool_c</a> ( Delete a variable from the kernel pool )
   <a href="../cspice/expool_c.html">expool_c</a> ( Confirm the existence of a pool kernel variable )
   <a href="../cspice/furnsh_c.html">furnsh_c</a> ( Furnish a program with SPICE kernels )
   <a href="../cspice/gcpool_c.html">gcpool_c</a> ( Get character data from the kernel pool )
   <a href="../cspice/gdpool_c.html">gdpool_c</a> ( Get d.p. values from the kernel pool )
   <a href="../cspice/getfov_c.html">getfov_c</a> ( Get instrument FOV configuration )
   <a href="../cspice/gipool_c.html">gipool_c</a> ( Get integers from the kernel pool )
   <a href="../cspice/gnpool_c.html">gnpool_c</a> ( Get names of kernel pool variables )
   <a href="../cspice/kdata_c.html">kdata_c</a>  ( Kernel Data )
   <a href="../cspice/kinfo_c.html">kinfo_c</a>  ( Kernel Information )
   <a href="../cspice/ktotal_c.html">ktotal_c</a> ( Kernel Totals )
   <a href="../cspice/ldpool_c.html">ldpool_c</a> ( Load variables from a kernel file into the pool )
   <a href="../cspice/lmpool_c.html">lmpool_c</a> ( Load variables from memory into the pool )
   <a href="../cspice/pcpool_c.html">pcpool_c</a> ( Put character strings into the kernel pool )
   <a href="../cspice/pdpool_c.html">pdpool_c</a> ( Put d.p.'s into the kernel pool )
   <a href="../cspice/pipool_c.html">pipool_c</a> ( Put integers into the kernel pool )
   <a href="../cspice/stpool_c.html">stpool_c</a> ( String from pool )
   <a href="../cspice/swpool_c.html">swpool_c</a> ( Set watch on a pool variable )
   <a href="../cspice/szpool_c.html">szpool_c</a> ( Get size limitations of the kernel pool)
   <a href="../cspice/unload_c.html">unload_c</a> ( Unload a kernel )
 
 
 
</PRE>

</TD>
</TR>
</TBODY>
</TABLE>

</BODY>

</HTML>
